home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Deutsche Edition 1
/
Deutsche Edition 1.iso
/
amok
/
011-020
/
amok16
/
proginfoids
< prev
next >
Wrap
Text File
|
1993-11-04
|
11KB
|
318 lines
======================================================================
AMOK - Amiga Modula Klub Stuttgart
Standard Identifier für ProgInfo
(Dokumentationsextraktion aus dem Quelltext)
======================================================================
Programmkopf
Für alle AmokProgramme ist ein Programmkopf vorgeschrieben, der die
wichtigsten Informationen zu diesem enthält.
Bei Modula-2-Programmen muß er vor dem Schlüsselwort MODULE in einem
Kommentar stehen. Er sollte durch "***"- oder "---"-Zeilen hervorgehoben
sein, ein Einrahmen ist jedoch nicht zweckmäßig (da die letzten "*"s in
der Zeile stören).
Der Programmkopf enthält mehrere Einträge, die jeweils mit
":"Schlüsselwort"." beginnen. Reicht eine Zeile für einen Eintrag nicht
aus, wird das ":"Schlüsselwort"." in der nächsten Zeile wiederholt und
der Eintrag danach fortgesetzt. Doppelpunkt, Punkt und Schreibweise
sind wichtig, da sonst die Einträge von Doku-Extraktionsprogrammen nicht
gefunden werden.
Der Programmkopf muß (!) mindestens folgende Einträge enthalten:
:Program. <Programmname>
:Contents. <Kurzbeschreibung von Inhalt/Verwendungszweck>
:Author. <voller Autorenname, kein Pseudonym (!)>
:Copyright. <Bemerkung über Copyright oder Public Domain>
:Language. <Sprache, eventuell Bemerkung über Besonderheiten>
:Translator. <Name des Compilers/Assemblers mit Versionsangabe>
:History. <Version, Datum, Autor, Bemerkung>
Falls notwendig müssen auch folgende Angaben gemacht werden:
:Support. <Hinweis auf von anderen übernomene Programmteile/Ideen>
:Imports. <Importierte Module außer dem Standardumfang des Compilers>
:Bugs. <bekannte Fehler>
Freiwillig sind diese Angaben:
:Address. <Adresse des Autors>
:Phone. <seine Telephonnummer>
:Update. <Angaben über Änderungen, die :History. nicht abdeckt>
:Remark. <beliebiger Kommentar>
:Usage. <Usage zB. für CLI-Befehl>
Andere Einträge Date,Shortcut,Version sind möglichst nicht mehr zu
benutzen. Fehlende Einträge sollten so bald und gut als möglich
nachgetragen oder rekonstruiert werden.
Empfehlungen
Auf eine strikte festlegung des Programmkopftextes wurde verzichtet. Damit
dieser jedoch einigermaßen einheitlich bleibt sollte man die folgenden
Regeln beachten.
Leere Einträge
--------------
Außer den zuerst genannten Pflichteinträgen können eventuell auch welche
entfallen. Am besten läßt man dann den gesammten Eintrag sammt Schlüssel-
wort weg. Als leer gelten außerdem Einträge, die nur aus Leerzeichen,
Sternchen "*" oder Strichen "-" bestehen.
Unsinnige Einträge (zB. ":Imports. bis jetzt noch nichts") sind möglichst
zu unterlassen.
:Program.
---------
Hier sollte der Programmname stehen, der mit dem Filenamen (mit Extension,
zB. "Test.def") übereinstimmen sollte. Reicht der Programmname zur
eindeutigen Indentifizierung nicht aus (z.B. geändertes Modul "Strings")
so steht hinter dem Programmnamen ein entsprechender Kommentar.
:Contents.
----------
Kurzbeschreibung von Programminhalt und -funktion. Die Beschreibung
sollte erklärend sein und nicht nur eine längere Version des Programm-
namens sein (zB. N I C H T :
:Program. InOut.def
:Contents. Definitionsmodul Input/Output
).
:Author.
--------
Bitte den vollen Namen angeben. Pseudonyme sind unzulässig.
Ein Programm kann auch mehere Autoren haben, z.B. wenn ein PC-Programm
auf den Amiga umgesetzt wurde.
:Address.
---------
Freiwillig ist die Angabe der Adresse des Autors. Sie sollte Straße,
Hausnummer, Postleitzahl, Ort und Land enthalten.
:Phone.
-------
Telefonnummer des Autors mit Vorwahl. Zusätzliche Bemerkungen, zB. Zeit-
angaben für Erreichbarkeit, sind zulässig. Hat ein Programm mehere Autoren
(s. oben) so steht hier die Telefonnummer des für dieses Programm
zuständigen Autors, d.h. desjenigen, der eventuelle Fragen am besten
beantworten kann.
:Copyright.
-----------
Hieraus sollte ersichtlich sein, ob das Programm frei kopiert werden
darf (Public Domain), ob eine (Shareware-)Gebühr verlangt wird oder
ob das Programm gar nicht weitergegeben werden darf.
Kommentare wie zB. "copy it, but leave my name in" oder ähnliches sind
zulässig. Bei längeren "Plädoyers" sollte allerdings auf eine extra
Datei verwiesen werden.
:Language.
----------
Hier steht im Normalfall "Modula-2". Wenn das Programm INLINE-Assembler-
code enthält, sollte dies hier Vermerkt werden. Ebenso sollte verfahren
werden, wenn das Programm dem Modula-Standard nicht entsprechende
Statements enthält. Dazu gehört unter anderem die seit Version 3.2
mögliche Typenkonversion von ADDRESS/BPTR und die Dereferenzierung
von BPTRn (Zugriff auf BcplPtr^.items). Die normale Verwendung des
Typs BPTR als opaker Typ gehört nicht dazu, denn er ist im Standard-
Modula erlaubt.
Der Sinn hiervon ist es, Leute zu warnen, die Programme auf andere
Compiler umsetzen wollen.
:Translator.
------------
Bezeichnet den Compiler (/Assembler/Interpreter) (normal M2Amiga A+L)
und die Versionsnummer (V3.2d oder V3.1d). Dahinter stehen eventuelle
Hinweise auf Compiler-Bugs, die für dieses Programm relevant sind.
:History.
---------
Dies ist einer der wichtigsten Einträge. Er beinhaltet Informationen
über die Versionen des Programms (Opfer), der entsprechenden
Erstellungs- und Änderungsdaten (Tatzeit), den Autor oder für die
Änderung Veratwortlichen (Täter) sowie eine optionale Bemerkung
(Motiv). Beispiel:
:History. V1.1 [bne] 29.Mar.1989 (bug in Init() fixed)
Den Versionsnummern wird später noch ein spezielles Kapitel gewidmet.
Zusammengehörige Definitions- und Implementationsmodule tragen immer
mindestens gleiche Versions- und Revisionsnummer (Branchnummer und
Kennbuchstabe dürfen verschieden sein).
Das Datum besteht aus dem ein- oder zweistelligen Tag, dem Monats-
kürzel (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dez) aus drei
Buchstaben und der zwei oder vierstelligen Jahreszahl. Für den Autor
steht ein Kürzel oder für "Externies" der Nachname.
:Support.
---------
Der Fairneß halber sollte man hier Angaben über Beiträge anderer
Personen machen, wenn man Schuldgefühle wegen geklauter Ideen oder
Algorithmen hat.
:Imports.
---------
Importiert das Modul außer den Standardmodulen des Compilers noch
weitere, so müssen diese hier eingetragen werden. Wird eine bestimmte
Version benötigt, folgt auf den Namen des importierten Moduls dessen
Versionsnummer. Es dürfen auch Verweise auf Amok-Disks oder den Autor
gemacht wedren. Beispiel:
:Imports. MemSystem1.3 [bne], List [mif] Amok#7
:Bugs.
------
Sind Fehler eines Moduls bekannt, oder besteht der Verdacht, daß das
Modul fehlerhaft ist, wird dies hier vermerkt. Soweit dies möglich
ist, soll der Fehler möglichst eng eingegrenzt werden (z.B Angabe der
Prozedur, in der er auftritt). Ist ein Modul noch nicht vollständig
ausgetestet, sollte man mit ":Bugs. not tested" warnen. ":Bugs. none"
verpflichtet zu mindestens 99,9% Fehlerfreiheit!
:Usage.
-------
bezeichnet die Syntax eines CLI-Befehls und dessen Argumente.
Die Usage wird entweder in EBNF oder mit dem vom Dos-Handbuch und
ARP verwendeten Template angegeben.
Versionsnummern
---------------
Die Versionsnummer besteht normalerweise aus zwei Stellen
(version,revision), die durch einen Punkt getrennt sind. Die erste
lauffähige Version wird mit 1.0 bezeichnet. Bei jeder Änderung wird
die zweite Stelle (Revision) um eins erhöht, wobei nach 1.9 die 1.10
und dann 1.11 usw. folgt. Bei sehr tiefgreifenden Neuerungen wird die
erste Stelle (Version) erhöht, die zweite (Revision) springt auf 0.
Die Versionsnummer darf NICHT als Dezimalbruch angesehen werden,
der sich jedesmal um 1/10 erhöht. Eine Revision ist KEINE zehntel
Version und eine Version entspricht NICHT 10 Revisions. Version und
Revision werden unabhängig gezählt !!! Versionsnummern wie 1.09 sind
unzulässig und 1.10 (erste Version, zehnte Revision) steht zwischen
1.10 und 1.12 und ist nicht gleich 1.1 !
"Hundertstel" Versionen gibt es nicht. Wenn es erforderlich wird,
eine Version nachträglich in eine Reihe einzufügen, wird dies
durch eine zweiten Punkt gekennzeichnet.
Beispiel: Es existieren bereits die Versionen 1.0 bis 1.4 , und
jemand ändert nachträglich die Version 1.2 . Diese bekommt
dann die Nummer 1.2.1 (sog. Branch-Version).
Man kann Versionsreihen auch als Baum darstellen:
1.0
|
V
1.1
|
V
1.2
|
/ \
/ \
V V
1.3 1.2.1
| |
V V
1.4 1.2.2
| usw.
...
|
V
1.9
|
V
1.10
usw.
Die Zählweise entspricht nicht der von Big Blue, verleitet
aber dafür zu weniger Mißverständnissen, weil man nicht rätseln
muß, ob 3.2 jetzt die auf 3.1 oder auf 3.19 folgende Version ist.
Version und Revision können beliebig hoch werden - Beispiel:
die Libraries der alten 1.2 Workbench trugen die Versionsnummer
33.180 (dreiunddreißigste Version, hundertachzigste Revision).
Wer noch eine feiner abgestufte Unterscheidung machen möchte,
kann der Nummer noch einen Kleinbuchstaben anhängen. Dieser ist
optional und muß nichts über die Reihenfolge aussagen (z.B. 3.2d
für die deutsche und 3.2e für die englische Version).
Source-Code-Format
------------------
Damit der Sourcecode einigermaßen übersichtlich ist, wird folgende
Formatierung vorgeschlagen:
* In jeder Zeile steht nur eine logische Anweisungseinheit.
* Globale Prozeduren, Variablen und Konstanten stehen ganz am Anfang
der Zeile.
* Deklarationen und Prozedurkörper sind gegenüber ihrem CONST, VAR,
TYPE und PROCEDURE eingerückt.
* Programmteile, die lokal zu anderen definiert werden, oder von
bestimmten Konstrukten eingeschlossen werden, werden jeweils
relativ zu diesen um ZWEI Zeichen eingerückt.
* Zugehörige BEGIN und END, IF, ELSE und END usw. stehen jeweils
untereinander. Ist ein END mehr als eine Bildschirmseite (25 Zeilen)
von seinem BEGIN etc. entfernt, steht hinter dem END in Kommentar,
was dort beendet wurde.
* Außer nach VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN und EXIT
steht hinter jeder Zeile ein Semikolon.
* Elemente von Mengen, Aufzählungstypen und RECORDs fangen klein an,
Konstanten fangen klein oder groß an, alles andere immer groß.
Zusammengesetzte Wörter haben auch in der Mitte "GrossBuchstaben".
* Paßt die Parameterliste einer Prozedur nicht in eine Zeile
(75 Zeichen), werden die Parameter untereinander angeordnet.
* Importe werden alphabetisch nach den Namen der Module geordnet.
Sind Importlisten länger als zwei Zeilen werden auch die importierten
Objekte alphabetisch sortiert.
Beispiel:
CONST
welches=106;
PROCEDURE TuWas( Dies:Typ;
VAR Jenes:Art):BOOLEAN;
CONST
X=1;
Y=10;
VAR
Zähler:INTEGER;
BEGIN
FOR Zähler:=X TO Y DO
Action(Dies,Jenes);
END
RETURN Jenes=welches
END TuWas;
Alte Module müssen nicht sofort neu formatiert werden, von
Neuerscheinungen wird das obige Format allerdings gefordert.
Die Regeln werden ständig ergänzt.